Actionable comments posted: 2

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@bin/lib/onboard.js`:
- Around line 2159-2161: The compatibility notice loop using
getOpenshellCompatibilityNotice(gatewayEnv.IMAGE_TAG || null) is never reached
when startGatewayWithOptions returns early on healthy reuse; move or duplicate
the notice emission so it always runs regardless of gateway reuse. Specifically,
call getOpenshellCompatibilityNotice and log each line before invoking
startGatewayWithOptions (or ensure startGatewayWithOptions invokes a
callback/hook that prints the same lines on both new-start and healthy-reuse
paths) so the lifecycle boundary message is always printed.
- Around line 522-528: The getOpenshellCompatibilityNotice function currently
always returns informational text; update it to detect incompatible OpenShell
versions by comparing the passed version (version param) against the supported
NemoClaw↔OpenShell mapping (e.g., a supportedVersions array or mapping constant
you add) using semantic version checks (semver.satisfies or equivalent) and
return a warning message (or an array with a prominent warning line) when the
version does not satisfy the supported range; keep the existing informational
lines when compatible and ensure the function still handles null/unknown version
by returning a neutral notice.

---

Nitpick comments:
In `@docs/get-started/quickstart.md`:
- Line 57: Summary: The compatibility sentence uses passive past tense; change
it to active present-tense. Replace the current text "NemoClaw 0.1.0 was
validated with OpenShell 0.0.7." with an active present-tense phrasing such as
"NemoClaw 0.1.0 works with OpenShell 0.0.7." or "NemoClaw 0.1.0 validates
against OpenShell 0.0.7." Update that single sentence in the quickstart
paragraph to use active voice and present tense to comply with the docs style
rules.

In `@docs/reference/commands.md`:
- Line 69: The sentence uses passive voice ("NemoClaw 0.1.0 was validated
against"); change it to active voice by rewriting the clause to something like
"than the OpenShell release that NemoClaw 0.1.0 validates against" (locate the
sentence containing "NemoClaw 0.1.0 was validated against" in
docs/reference/commands.md and replace that passive clause with an active
construction referencing NemoClaw 0.1.0 validating the release).

@13ernkastel Thanks for putting this togethe, the OPENSHELL_COMPATIBILITY map, the helper decomposition, and the structural ordering test are all well thought out. This is a solid foundation for addressing #1261.

I've gone through the diff in detail and have a few findings below, grouped by priority.

Must fix

1. npm update -g openshell is missing from the code notices

The docs (README, quickstart, commands.md) list 4 dangerous commands, but the CLI warning and informational notices only list 3 — npm update -g openshell is missing from the code output. This is arguably the most common accidental upgrade path.

Docs say:

Avoid openshell self-update, npm update -g openshell, openshell gateway start --recreate, or openshell sandbox create

Code says:

Avoid openshell self-update, openshell gateway start --recreate, or openshell sandbox create

Both getOpenshellCompatibilityNotice return paths need npm update -g openshell added.

2. Passive voice still unfixed (CodeRabbit flagged this)

• quickstart.md: "NemoClaw 0.1.0 was validated with OpenShell 0.0.7"
• commands.md: "was validated against"

Repo docs style requires active voice. Suggest: "NemoClaw 0.1.0 requires OpenShell 0.0.7" or "NemoClaw 0.1.0 targets OpenShell 0.0.7".

3. No test that NEMOCLAW_VERSION exists in OPENSHELL_COMPATIBILITY

If someone bumps package.json to 0.2.0 without updating the map, getSupportedOpenshellVersions() returns [], formatSupportedOpenshellVersions([]) returns null, and the condition version && supportedLabel && !isSupportedOpenshellVersion(...) is always false. The entire compatibility check silently does nothing. A one-line test would prevent this:

it("tracks the current NemoClaw version in the compatibility map", () => {
  const { version } = require("../../package.json");
  expect(getSupportedOpenshellVersions(version).length).toBeGreaterThan(0);
});

4. .agents/skills/nemoclaw-overview/references/how-it-works.md still has the old guidance

The PR updates docs/about/how-it-works.md but there's a duplicate at .agents/skills/nemoclaw-overview/references/how-it-works.md that still says:

"For users without an existing OpenClaw installation, NemoClaw recommends openshell sandbox create directly rather than forcing a plugin-driven bootstrap."

This directly contradicts the PR's intent. An AI agent referencing this skill file would give users the old, dangerous advice.

Should fix

5. Mismatch warning goes to console.log (stdout) instead of console.warn (stderr)

The compatibility warning is printed via console.log. For CI/CD pipelines and scripts that parse stdout, this mixes warnings into normal output. The mismatch path should use console.warn or console.error so it goes to stderr. The informational (happy-path) notice is fine on stdout.

6. Informational notice is noisy on the happy path

When versions match, users see 2 lines of "everything is fine but here's a reminder" output on every onboard:

  OpenShell compatibility: NemoClaw derives the gateway image from the installed openshell CLI (0.0.7).
  Use `nemoclaw onboard` to recreate NemoClaw-managed sandboxes, and avoid ...

Consider making the happy path silent (or a single short line like ✓ OpenShell 0.0.7 (compatible)) and only being verbose when there's a problem.

7. Null version notice should be more explicit

When openshell -V fails, the notice says "NemoClaw derives the gateway image from the installed openshell CLI" — a calm informational message. A missing/broken OpenShell during onboard is itself a problem. Consider: "Could not detect installed OpenShell version — verify openshell -V works before proceeding."

Minor / follow-up

8. formatSupportedOpenshellVersions grammar for 2-item lists

For ["0.0.7", "0.0.8"] it returns "0.0.7, or 0.0.8" — the comma before "or" is incorrect with only 2 items. Should be "0.0.7 or 0.0.8". Oxford comma applies for 3+ items only.

9. Structural source-code test is fragile

The test that regex-matches startGatewayWithOptions function body and uses indexOf to verify ordering is clever but brittle. A rename or refactor breaks the test without breaking the feature. Consider an integration-style test that captures console output instead.

10. Pre-release versions in package.json silently disable the check

If package.json ever has "0.2.0-beta.1", the map lookup returns undefined and the check silently disables (same root cause as #3 but via a different trigger).

Overall this is heading in the right direction. Thanks again for the thorough work here.

Thanks @13ernkastel — all 10 items from the previous review are addressed. Nice work on the turnaround.

Quick summary of what was fixed in d55083c7:

• npm update -g openshell consistency — extracted OPENSHELL_DIRECT_COMMANDS constant so docs and code list the same 4 commands everywhere
• Passive voice — "was validated with" → "supports" across README, quickstart, and commands.md
• Version map guard test — test reads package.json and asserts the current version exists in OPENSHELL_COMPATIBILITY, so a version bump without updating the map fails CI
• Stale .agents/skills/ copy — updated to match the new "OpenShell-backed lifecycle" guidance (plus several other skill files updated for consistency)
• Warning to stderr — getOpenshellCompatibilityLevel() routes mismatches through console.warn, happy path stays on console.log
• Happy path noise — collapsed to a single line when versions match
• Null version handling — now explicitly warns "Could not detect the installed openshell CLI version"
• 2-item grammar — "0.0.7 or 0.0.8" (no errant comma), with tests for 1, 2, and 3-item lists
• Fragile structural test replaced — integration test spawns a real child process with a mock openshell binary, verifies output ordering at runtime
• Pre-release version support — parseSemver accepts [-+] suffixes, getSupportedOpenshellVersions normalizes before map lookup, test confirms "0.1.0-beta.1" resolves correctly

The missing-map-entry case now also emits an explicit warning ("does not declare a supported OpenShell baseline") instead of silently disabling the check — good defensive addition.

Only remaining item is --strict enforcement for CI, which we agreed is a follow-up. LGTM.

Actionable comments posted: 1

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.agents/skills/nemoclaw-reference/references/troubleshooting.md:
- Around line 98-109: This .agents/skills file is autogenerated and must not be
edited directly; instead update the original source docs file
docs/reference/troubleshooting.md with the desired content (e.g., the
Docker/Podman onboarding notes) and then regenerate the skill by running the
generator script scripts/docs-to-skills.py so it updates
.agents/skills/nemoclaw-reference/references/troubleshooting.md; do not commit
direct edits to the autogenerated file.

---

Outside diff comments:
In @.agents/skills/nemoclaw-deploy-remote/SKILL.md:
- Around line 1-188: The PR edited an autogenerated skill file
(.agents/skills/nemoclaw-deploy-remote/SKILL.md) which must not be changed
directly; revert your edits to that file, make the documentation changes in the
corresponding source under docs/ (the original markdown that feeds this skill),
and regenerate the skill by running the generator script
scripts/docs-to-skills.py (e.g., python scripts/docs-to-skills.py) so the
updated content is produced into .agents/skills/nemoclaw-deploy-remote/SKILL.md.

In @.agents/skills/nemoclaw-reference/references/commands.md:
- Around line 1-249: The PR edited an autogenerated skill file
(.agents/skills/nemoclaw-reference/references/commands.md) which must not be
modified directly; revert any changes to that file and instead update the
canonical source docs/reference/commands.md, then run the generation script
scripts/docs-to-skills.py (e.g., python scripts/docs-to-skills.py) to regenerate
.agents/skills/nemoclaw-reference/references/commands.md so the change flows
through the proper build step.